home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / bitwise / bitwise.doc < prev    next >
Encoding:
Text File  |  1995-02-25  |  11.0 KB  |  274 lines
  1. BitWise, v1.0                                          BITWISE.DOC
  2. by Shawn Bayern
  3.  
  4. ==================================================================
  5. Introduction:
  6.  
  7.      BitWise is a Turbo Pascal 7.0 unit that allows you to compress
  8. boolean data by a factor of 8.  Turbo Pascal's "boolean" type uses
  9. 8 bits (1 byte) to store a value of either "TRUE" or "FALSE";
  10. however, while the boolean data type is fast and relatively
  11. efficient, only 1 bit is truly necessary to store a "boolean-like"
  12. value.
  13.      The procedures and functions contained in the unit BitWise
  14. allow use you to use an array of bytes to store boolean values. 
  15. Each byte contains 8 bits, and each of these bits can store an
  16. individual value.  While some speed is sacrificed (since the data
  17. has to be found and decoded), an effective compression factor of 8
  18. is achieved.  (While speed is sacrificed for some purposes, you
  19. might find that BitWise actually *saves* time in some cases; if
  20. data is being moved around a lot within your program, or if you
  21. need to deal with large amounts of data at once, BitWise can
  22. actually speed up some operations).
  23.      BitWise is shareware.  You may freely distribute it, and you
  24. may use it for any noncommercial, private (i.e., non-institutional)
  25. purposes.  For commercial (including use in shareware products) or
  26. institutional usage, the $10 registration fee must be paid.  The
  27. source code will be provided to all users who register.
  28.  
  29. ==================================================================
  30. Disclaimer:
  31.  
  32.      You are using BITWISE.TPU at your own risk.  I take no
  33. responsibility for the use or misuse of BitWise.  No guarantee,
  34. expressed or implied, is made concerning the accuracy of this
  35. documentation or concerning the correct operation of the routines
  36. contained in BITWISE.TPU.  If the routines contained in BITWISE.TPU
  37. do not work as expected, the author is not to be held responsible.
  38.  
  39. ==================================================================
  40. Instructions:
  41.  
  42.      To use BitWise, you must first place the BITWISE.TPU unit in
  43. a directory where Turbo Pascal will find it.  In every program that
  44. you plan to use BitWise, you must "use" it as follows:
  45.  
  46. uses BitWise;
  47.  
  48.      For further instructions regarding unit usage, please see the
  49. Turbo Pascal documentation.
  50.  
  51.      Next, you must define an array of bytes to store your "pseudo-
  52. pseudo-boolean" data.  This array should contain one-eight as many
  53. elements as the number of boolean values you wish to store. 
  54. Consider the following examples:
  55. var
  56.    MyArray: array[1..100] of byte; {stores 800 bits}
  57.    MyArray2: array[1..2000] of byte; {stores 16000 bits}
  58.  
  59.      If you plan on using eight bits or fewer, you can simply
  60. define a "byte" value:
  61.  
  62. var
  63.    TestByte: byte;
  64.  
  65.      It is usually inadvisable to use BitWise for only eight bits;
  66. however, if you plan on moving the data extremely many times,
  67. BitWise might save you time.
  68.  
  69.      Now that you have the appropriate variables defined, you can
  70. begin to use the BitWise procedures and functions.
  71.  
  72.      The interface section of BITWISE.TPU is as follows (a detailed
  73. explanation of each procedure and function will follow this
  74. listing):
  75.  
  76. *** interface
  77. *** 
  78. *** type
  79. ***    BitValue=0..1;
  80. *** 
  81. *** procedure SetElement(var BigArray: array of byte; const Elem:
  82. ***                      longint);
  83. *** procedure ResetElement(var BigArray: array of byte; const Elem:
  84. ***                        longint);
  85. *** function Element(const BigArray: array of byte; const Elem:
  86. ***                  longint): boolean;
  87. *** procedure ToggleElement(var BigArray: array of byte; const
  88. ***                         Elem: longint);
  89. *** procedure AssignElement(var BigArray: array of byte; const
  90. ***                      Elem: longint; const ElemValue: BitValue);
  91. *** function BoolToBit(const BoolArray: array of boolean;
  92. ***                    var BitArray: array of byte): byte;
  93. *** function BitToBool(const BitArray: array of byte;
  94. ***                    var BoolArray: array of boolean): byte;
  95.  
  96. Explanation:
  97.  
  98.      First, I'm going to explain how data is stored in your array
  99. of bytes; then, I'll show how each of these routines can be used.
  100.  
  101.      Let's consider an array[1..100] of byte.  As I already
  102. explained, this array contains 800 bits.  The procedures and
  103. functions in BitWise manipulate these bits directly.  For the
  104. purposes of BitWise, it's best to think of these bits as being
  105. numbered from 1 to 800.  More generally, if you're dealing with N
  106. bits, then these bits are numbered from 1 to N -- *regardless* of
  107. the numbers that you use to index your array.
  108.  
  109.      For instance, if you define
  110.  
  111. var
  112.    MyArray: array[2..5] of byte; {40 bits}
  113.  
  114. then the 40 bits will still be numbered from 1 to 40.  Again,
  115. BitWise doesn't care about the index numbers of your arrays.  It
  116. looks upon all arrays as just a sequential series of bytes
  117. beginning with one byte and ending with another.
  118.  
  119. ------------------------------
  120.  
  121.      Now, on to the discussion of the procedures and functions in
  122. BitWise.  For the rest of this section, we're going to refer to the
  123. following array:
  124.  
  125. var
  126.    TestArray: array[1..100] of byte; {800 bits}
  127.  
  128.      Procedure SetElement can be used to "turn on" a bit in the
  129. array.  If you want to turn on the 123rd bit, then you simply call
  130. SetElement as follows:
  131.  
  132.      SetElement(TestArray, 123);
  133.  
  134. Now, bit #123 of TestArray has a value of "1."  
  135.  
  136. ------------------------------
  137.  
  138.      Procedure ResetElement "turns off" a bit in the array.  If you
  139. want to turn off the 123rd bit, then you can call ResetElement as
  140. follows:
  141.  
  142.      ResetElement(TestArray, 123);
  143.  
  144. Now, bit #123 of TestArray has a value of "0."
  145.  
  146. ------------------------------
  147.  
  148.      If you wish to check whether an element is "on" or not, you
  149. can use the function Element as follows:
  150.  
  151.      If Element(TestArray, 123) then
  152.         Writeln('Element 123 of TestArray is "on."');
  153.  
  154. Note that the syntax of "Element" is designed to mimic the usual
  155. usage of a boolean type.  If you were dealing with an array of
  156. boolean variables, you would use:  "If BooleanArray[counter] then
  157. ..."  The function, "Element," should make bitwise checking as
  158. simple as possible.
  159.  
  160. ------------------------------
  161.  
  162.      If you want to toggle a bit in your array, use the 
  163. ToggleElement procedure as follows:
  164.  
  165.      ToggleElement(TestArray, 123);
  166.  
  167. If element #123 was "1," it is now "0," and vice-versa.
  168.  
  169. ------------------------------
  170.  
  171.      While you can use SetElement, ResetElement, and ToggleElement
  172. to manipulate bits in your array, you might want to define a bit
  173. directly (i.e., "pass" a value to a bit).  To do this, you can use
  174. AssignElement:
  175.  
  176.      AssignElement(TestArray, 123, 1); {bit #123 now equals 1}
  177.      AssignElement(TestArray, 123, 0); {bit #123 now equals 0}
  178.  
  179. You may have noticed the data type "BitValue" in the interface
  180. section of BITWISE.TPU.  Not much needs to be said about it; it is
  181. used here only in the procedure AssignElement.  It just checks to
  182. make sure that a valid value (a 1 or a 0) is being passed to the
  183. bit to which you're assigning a value.
  184.  
  185. ------------------------------
  186.  
  187.      The procedures and functions just described give you complete
  188. control over the bits in your array.  Two more functions are
  189. provided for flexibility; these functions allow you to convert your
  190. array of bytes into a standard boolean array (which is eight times
  191. large) and back.  Note the following examples:
  192.  
  193. uses BitWise;
  194.  
  195. var
  196.    TestArray: array[1..100] of byte; {800 bits}
  197.    BigArray: array[1..800] of boolean;
  198.  
  199. begin
  200.    BitToBool(TestArray,BigArray);
  201.      {this copies the data in TestArray to BigArray.  For instance,
  202.      if the first three bits in test array (bits #1, #2, and #3)
  203.      are "1 0 1" respectively, then BigArray[1] becomes "True,"
  204.      BigArray[2] becomes "False," and BigArray[3] becomes "True."}
  205.    BoolToBit(BigArray,TestArray);
  206.      {does the opposite procedure; if BigArray[1] is "true" then
  207.      bit #1 of TestArray becomes "1"}
  208. end.
  209.  
  210. NOTE:  Since BitToBool and BoolToBit are functions, not procedures,
  211. this program will run only if Turbo Pascal's extended syntax is
  212. "on" {$X+}.  Since X+ is the default, it shouldn't be a problem; it
  213. merely allows functions to be called as if they were procedures
  214. (and the return values are discarded).
  215.      You can run BitToBool and BoolToBit as procedures, like in the
  216. example above.  However, if your program is more complex and you
  217. want slight error checking, you might want to look at the return
  218. values of these two functions.  Both BitToBool and BoolToBit return
  219. a "0" if the boolean array was exactly 8 times as large as the byte
  220. array (meaning that the target array is exactly large enough to
  221. contain the data in the source array).  BitToBool and BoolToBit
  222. still work even if the boolean array is *not* exactly 8 times as
  223. large as the byte array; however, in this case, they return a "1." 
  224. It's up to you to determine how you wish to use BitToBool and
  225. BoolToBit; they're pretty flexible, but they don't catch any
  226. errors, so be careful (and test your program to make sure that the
  227. data is copied in the way you expect, if the boolean array is not
  228. exactly 8 times larger than the byte array).
  229.  
  230. ------------------------------
  231.  
  232.      Technical note:  Within each byte, the bits are ordered as
  233. follows: #7  #6  #5  #4  #3  #2  #1  #8.  For instance, if elements
  234. 1 through 8 are "1111 0000," then the first byte will read as
  235. follows:  "0001 1110."  Using these routines, you never have to
  236. worry about this order; however, you might wish to know it if you
  237. plan to write your own support routines.
  238.      There's no particular reason for this order; it just allowed
  239. the algorithm that I was using to work more quickly than some other
  240. orders.  I originally tried "1 2 3 4 5 6 7 8," but that was
  241. slightly slower.
  242.  
  243. ==================================================================
  244. Registration:
  245.  
  246.      As I mentioned above, the registration fee is $10.  If you
  247. wish to register, please send checks made out to "Shawn Bayern" to:
  248.  
  249. Shawn Bayern
  250. 5 Cedarwood Court
  251. Laurel Hollow, NY 11791.
  252.  
  253. My phone number is (516)-367-9038, and my e-mail address is
  254. "bayern@cshl.org" if you wish to contact me.
  255.  
  256.      All registered users will receive a copy of the source code to
  257. BITWISE.TPU.  If you use BitWise, please support the shareware
  258. concept and register.  (If you're using BitWise in a commercial or
  259. institutional environment, you have a legal obligation to regis-
  260. ter.)
  261.  
  262. ==================================================================
  263. Copyright Notice:
  264.  
  265. BitWise--including BITWISE.TPU and this documentation file--are
  266. copyright 1995, Shawn Bayern.  Permission is granted to freely
  267. distribute this file provided that neither BITWISE.DOC nor
  268. BITWISE.TPU are modified in any way.
  269.      It is prohibited to disassemble or otherwise reverse-engineer
  270. BITWISE.TPU, or to remove the BitWise copyright notice from
  271. programs that use BitWise.  (Programs that use bitwise will contain
  272. a brief copyright message somewhere within them; a tiny bit of code
  273. to check that this copyright message has not been altered is
  274. included as well).